MACD 5 (Alt)/MACD 5.bin/workbench/wb/czesc_2/iconmiser/iconmiser.doc

Text File | 1994-01-11 | 7.7 KB | 185 lines

PROGRAM: IconMiser 2.0

AUTHOR:  Todd M. Lewis                 E-MAIL: [e-mail]
         2601 Piedmont Drive
         Sanford, NC  27330-9437  USA

IconMiser is a utility which monitors the creation of icons. When
a program attempts to create an icon that looks like one on your
hit list, IconMiser substitutes the icon or icon image of your
choice.


DISTRIBUTION

Sure, go ahead.  I didn't write these docs for myself, ya know.


RUNNING THE PROGRAM

The program can be run from Workbench or the CLI.  It can take
three parameters: NOWINDOW, QUIT, and a possible file name.

  "Nowindow" tells the program not to bring up the user
             interface.  One way to set up your system is to
             include the line "IconMiser NOWINDOW" in your
             S:User-Startup or S:Startup-Sequence file.
             Another way is to move the IconMiser.prefs file to
             your WBStartup drawer and include the "NOWINDOW"
             tooltype.  ("NOWINDOW=" is necessary for pre-2.0
             systems.)

  "Quit"     is useful if you want to unload IconMiser's
             background utility.  This is necessary if you want
             to shut down Workbench.

Any other parameter is taken as the name of a configuration file.
If none is given and IconMiser's background utility is not
already running, a configuration file is searched for and loaded
if found.  The program first looks for the file "IconMiser.prefs"
in the current directory, then "ENV:IconMiser/IconMiser.prefs",
and finally "S:IconMiser.prefs".


WINDOW LAYOUT AND CONTROLS

IconMiser presents a window with two icon holding areas labeled
"From" and "To" with attached string gadgets for entering the
names of icons.  (Don't include the ".info" part of the icon file
names.) If you are running 2.04 or above, you can drag icons from
Workbench windows and drop them into the icon drop boxes and
never have to type an icon's file name.

The cycle gadget below the icons lets you specify how you want
IconMiser to operate when a program attempts to save an icon with
an image that matches the "From" icon's image.  (The match is
only made on the unselected image.)  You get four choices:

  Substitute Image Only  Creates an icon with all the settings of
                         the "From" icon (type, stack size, etc)
                         but uses the image from the "To" icon.

  Substitute Whole Icon  Uses the "To" icon (image, position,
                         stack size, type, default tool, etc) in
                         place of the "From" icon.

  Use From Icon As Is    Acts as if the image didn't match.  This
                         allows you to temporarily disable
                         substitution on a pair of icons without
                         removing from it from the configuration.

  Make No Icon At All    Prevents the creation of the icon
                         altogether.  This is handy for programs
                         that insist on creating icons even if
                         you don't want them to.  Note that you
                         will still have to specify a "To" icon
                         even though it won't be used.

Just below the cycle gadget are three pairs of buttons.  They do
the following things:

  Prev      These buttons allow you to move back and forth
  Next      through the "From/To" pairs of icons.  There is no
            practical limit to how many pairs of icons you can
            specify, but the "From" icons will be unique.  That
            is to say that if you create a pair of icons and the
            "From" icon's unselected image is identical to that
            of another "From" icon, the other pair is quietly
            removed.

  New       These two buttons allow you to create a New pair of
  Delete    icons, or Delete the currently displayed pair.  There
            is no warning on the Delete button, and no UnDo
            function, so don't delete a pair from the list unless
            you really mean to.  You have been warned.

  Keep      These buttons allow you to add the new or modified pair
  Revert    of icons, along with their action mode, to the active
            list the program is currently using, or to Revert
            back to the way it was before you started making
            changes.

Across the bottom are three more gadgets: Save, Use, and Load.

  "Save" saves the configuration (i.e., all the icon pairs and
  their change modes) to "the right place" and closes the window.
  "The right place" is where the configuration was loaded from
  last, or ENVARC:IconMiser/IconMiser.prefs and
  ENV:IconMiser/IconMiser.prefs if those directories exist, or else
  to S:IconMiser.prefs.

  "Use" saves the configuration to ENV:IconMiser/IconMiser.prefs if
  it can, then closes the window.

  "Load" brings up a file requester (or just a string gadget if you
  are running a pre-2.04 system) for you to specify a configuration
  to load.  Note that the icon pairs in the loaded configuration
  are added to those already in the program.  Only pairs whose
  "From" icon matches a "From" icon in the configuration file
  will be replaced by the pairs in the file.


MENUS

IconMiser presents a Project menu and an Icon menu.  The Project
menu items are:

  Open...      Same as the "Load" button on the window.  See above.

  Save As...   Brings up a file requester (or a string gadget if you
               are running a pre-2.04 system) for specifying a
               name for the configuration file to save.

  About...     Brings up a brief requester with a little
               information about the program.  Same as the help
               key.

  Quit         Closes the window (same as the Close Gadget).  It
               does not shut down the background utility.  Icon
               substitutions will still be made.

The Icons menu has two menu items: "Save From Icon..." and "Save
To Icon..."  These allow you to save the displayed "From" or "To"
icons to disk where you can then change their attributes or
otherwise do with them as you wish.  Don't specify the ".info"
part of the file names--the system adds that for you.


TECH NOTES

IconMiser works by patching the PutDiskObject vector of
icon.library.  Whenever PutDiskObject is called, the unselected
image of the DiskObject is compared to those of the "From" icons
in the list, and appropriate substitutions are made if a match is
found.

There is no fool-proof way of "unpatching" a library vector,
though every attempt is made to keep things safe when unloading
the background utility.  It is necessary to unpatch the library
vector in order to cleanly shutdown Workbench.  Though I have
not been able to make it fail after extensive testing, I cannot
guarantee there will be no problems on your system when running
the command "IconMiser QUIT".  If you run "IconMiser QUIT" and
the background utility is not already running, you will get
a brief message to that effect.

The background utility, called PDO_Patch, is imbedded within
IconMiser itself.  It is written out to the T: directory and run
from there if it isn't already running.  Both PDO_Patch and
IconMiser detach themselves from their parent processes, so
including IconMiser in one of the startup scripts doesn't present
a problem when closing down the initial CLI.

The configuration file or .prefs file is an unregistered
IFF-conforming file.  It is a CAT ICNM of FORM IMSRs with chunk
types DOBP, DOBF, and DOBT.  DOBP consists of a ULONG containing
the action type for this IMSR.  DOBF and DOBT are byte for byte
copies of the icons as found on disk.

Reading and writing of the configuration files requires temporary
creation of icons in the T: directory.  This is normal, but can
generate an interesting display if you have the T: directory
window open when saving a configuration.